StringAssign Routine ---------------------------------------------------------------------------- Action Used in mixed-language programming to transfer string data from one language's memory space to that of another. Syntax StringAssign( sourceaddress&, sourcelength%, destaddress&, destlength%); Remarks The syntax above is for the C language. However, the order of the arguments in the syntax follows BASIC, Pascal and FORTRAN calling conventions rather than the C calling convention. (In BASIC, Pascal and FORTRAN, the arguments are passed in the order in which they appear in the source code. In C, the arguments are passed in the reverse order.) For MASM, Pascal, and FORTRAN examples, see Chapter 13, "Mixed-Language Programming with Far Strings" in the Programmer's Guide. The StringAssign routine uses the following arguments. ----------------------------------------------------------------------------- Argument Description ---------------------------------------------------------------------------- sourceaddress& The far address of the start of string data (if the source is a fixed-length string), or the far address of the string descriptor (if the source is a variable-length string). The sourceaddress& is a long integer. sourcelength% The string length (if the source is a fixed-length string), or 0 (if the source is a variable-length string). The Argument Description ---------------------------------------------------------------------------- variable-length string). The sourcelength% is an integer. destaddress& The far address of the start of string data (if the destination is a fixed-length string), or the far address of the string descriptor (if the destination is a variable-length string). The destaddress& is a long integer. destlength% The string length (if the destination is a fixed-length string), or0 (if the destination is a variable-length string). The destlength% is an integer. The StringAssign routine is used in mixed-language programming to transfer a string from BASIC to a non-BASIC routine or from a non-BASIC routine to BASIC. A typical use is to transfer a string from BASIC to a non-BASIC routine, process the string using the non-BASIC routine, and then transfer the modified string back to BASIC. Calls to the StringAssign routine are usually made from a C, MASM, Pascal, or FORTRAN routine. Seldom, if ever, would you call StringAssign from inside a BASIC program. StringAssign can be used to transfer both near and far strings. Using StringAssign, you can write mixed-language programs that are near-string-far-string independent. MASM, C, Pascal, and FORTRAN deal only with fixed-length strings. When programming in these languages you can use StringAssign to create a new BASIC variable-length string and transfer fixed-length string data to it. For example, to transfer a MASM fixed-length string containing the word "Hello" to a BASIC variable-length string, you would use the following data structure. fixedstringdb "Hello" ; source of data descriptor dd 0; descriptor for destination The second data element, descriptor, is a 4-byte string descriptor initialized to zero. BASIC interprets this to mean that it should create a new variable-length string and associate it with the address labelled descriptor. To create a new BASIC variable-length string and transfer fixed-length data to it, the StringAssign routine requires four arguments. - The far address of the fixed-length string in the MASM data segment. - The length of the fixed-length string in the MASM data segment. - The far address of the string descriptor in the MASM data segment. - 0 (to indicate that the string in the BASIC data segment will be a variable-length string). The following MASM code pushes these arguments on the stack and calls StringAssign. pushds; segment of fixed-length string lea ax, fixedstring ; offset of fixed-length string pushax mov ax, 5; length of "Hello" pushax pushds; segment of descriptor lea ax, descriptor ; offset of descriptor pushax mov ax, 0 ; 0 = variable-length string pushax extrnstringassign. proc far callstringassign When the call to StringAssign is made, BASIC will fill in the double-word descriptor with the correct string descriptor. Note When creating a new variable-length string, you must allocate 4 bytes of static data for a string descriptor as shown above. Allocating the data on the stack will not work. For more information on mixed-language programming with strings, see Chapter 12, "Mixed-Language Programming" and Chapter 13, "Mixed-Language Programming with Far Strings" in the Programmer's Guide. See Also StringAddress, StringLength, StringRelease Example The following example shows how to use StringAssign and StringRelease, routines in the BASIC main library. The program gets a MASM string and prints it on the screen. DEFINT A-Z ' Declare external MASM procedures. DECLARE FUNCTION MakeString$ DECLARE SUB ReleaseIt ' Get string from MASM and print it. PRINT MakeString ' Have MASM release the variable-length string it created. CALL ReleaseIt The following MASM procedure must be assembled and the .OBJ file linked to the BASIC code listed above. ; ************************** MakeString *************************** ; Create a fixed-length string and assign it to a BASIC ; variable-length string. Release the string after BASIC uses it. .model medium, basic ; Use same model as BASIC. .data ; Create MASM string and a place for BASIC to create a ; variable-length string descriptor. String2db "This is a string created by MASM." Descriptor dd 0 .code ; Declare BASIC library routines to be used. extrnStringAssign. proc far extrnStringRelease. proc far MakeString proc; Push arguments. pushds; MASM string segment lea ax, String2; MASM string offset pushax mov ax, 33; MASM string length pushax pushds; BASIC descriptor segment lea ax, Descriptor pushax; BASIC descriptor offset xor ax, ax; Variable-length indicator pushax callStringAssign; Assign the string. lea ax, descriptor ; Return with descriptor ret ; address in AX. MakeString endp ReleaseIt proc; Routine to release lea ax, Descriptor ; the string. pushax callStringRelease ret ReleaseIt endp end